docs(cards): PATCH /cards/{id} is platform-authenticated, not SCA-railed - #799
docs(cards): PATCH /cards/{id} is platform-authenticated, not SCA-railed#799kphurley7 wants to merge 2 commits into
Conversation
The spec described a 202 -> signed-retry flow that the implementation never had. Rather than build it, drop it: the pattern signs with the session key of a credential on the owning internal account, so requiring it would make a platform unable to freeze or close a card without the cardholder present - which is exactly the fraud-response and offboarding case the verb exists for. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JsJUrc9YRcfxEFqgXQEYvD
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
The split source edit (drop the 202 -> signed-retry flow on PATCH /cards/{id})
was not reflected in the compiled openapi.yaml / mintlify/openapi.yaml, so the
"Build OpenAPI Documentation" check failed on out-of-sync bundles. Regenerated
via `make build`.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1EQw7zvv37yerH6cccwrV
github-actions
Bot
added
the
breaking-change
|
✱ Stainless preview builds for gridThis PR will update the cli go kotlin openapi php python ruby typescript Edit this comment to update them. They will appear in their respective SDK's changelogs. ✅ grid-typescript studio · code · diff
✅ grid-openapi studio · code · diff
✅ grid-ruby studio · code · diff
✅ grid-go studio · code · diff
✅ grid-kotlin studio · code · diff
✅ grid-php studio · code · diff
✅ grid-cli studio · code · diff
⏳ These are partial results; builds are still running. This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push. |
Greptile SummaryThe PR revises
Confidence Score: 4/5The PR should not merge until the generated OpenAPI bundles and card guides are synchronized with the revised endpoint contract. The source operation now advertises direct platform-authenticated updates, while tracked bundles and user-facing guides still publish the removed signed-retry flow, and the repository’s consistency check will fail. Files Needing Attention: openapi/paths/cards/cards_{id}.yaml, openapi.yaml, mintlify/openapi.yaml, and mintlify/snippets/cards/
|
| Filename | Overview |
|---|---|
| openapi/paths/cards/cards_{id}.yaml | The operation is internally consistent after removing signed retry, but the source-only edit leaves required generated bundles and related guides stale. |
Prompt To Fix All With AI
### Issue 1
openapi/paths/cards/cards_{id}.yaml:73-76
**Generated card contract remains stale**
When this source-only change enters the normal build and publishing workflows, the committed OpenAPI bundles and card guides retain the removed signing headers, `202` response, and signed-retry instructions, causing the consistency check to fail while SDK previews and readers receive a contract that contradicts this operation. Rebuild the tracked bundles and update the related card snippets with this change.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "docs(cards): PATCH /cards/{id} is platfo..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| This endpoint is authenticated by the platform credential alone and | ||
| returns `200` directly. It deliberately does not use Grid's 202 → | ||
| signed-retry pattern: that pattern signs with the session key of a | ||
| credential on the owning internal account, so it models actions taken |
There was a problem hiding this comment.
When this source-only change enters the normal build and publishing workflows, the committed OpenAPI bundles and card guides retain the removed signing headers, 202 response, and signed-retry instructions, causing the consistency check to fail while SDK previews and readers receive a contract that contradicts this operation. Rebuild the tracked bundles and update the related card snippets with this change.
Context Used: CLAUDE.md (source)
Knowledge Base Used: Cards
Prompt To Fix With AI
This is a comment left during a code review.
Path: openapi/paths/cards/cards_{id}.yaml
Line: 73-76
Comment:
**Generated card contract remains stale**
When this source-only change enters the normal build and publishing workflows, the committed OpenAPI bundles and card guides retain the removed signing headers, `202` response, and signed-retry instructions, causing the consistency check to fail while SDK previews and readers receive a contract that contradicts this operation. Rebuild the tracked bundles and update the related card snippets with this change.
**Context Used:** CLAUDE.md ([source](https://github.com/lightsparkdev/grid-api/blob/main/CLAUDE.md))
**Knowledge Base Used:** [Cards](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/cards.md)
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.1 participant
Reason
PATCH /cards/{id}documented a202-> signed-retry flow that the implementation never had: it returns200directly, authenticated by the platform credential. One of the two has to give.The spec should give, because the documented flow is wrong for this verb. The 202 pattern signs the challenge with the session private key of a verified authentication credential on the card's owning internal account - the end user's key. That models actions taken by a user on their own credentials or funds, which is why
DELETE /auth/credentials/{id}andPOST /internal-accounts/{id}/exportuse it.Freezing or closing a card is routinely an action taken about a user and without them present: fraud response, offboarding, an ops-driven freeze. Under the documented flow none of those are possible through the public API, and the cardholder may be the adversary. We would have had to add a platform-authenticated bypass almost immediately, and that bypass would have become the path everyone actually used.
Overview
Grid-Wallet-SignatureandRequest-Idheader parameters.202response.200is no longer described as "signed retry accepted".401description, which described signature and challenge failures.Sensitive-data operations stay SCA-railed:
POST /cards/{id}/revealand 3DS password retrieval are unchanged, because there the cardholder is the party being served and user-present signing is the right model.Notes
No implementation change accompanies this - sparkcore already behaves this way, so this closes the divergence rather than opening one. Nothing is affected downstream: the card program is gated behind
GRID_CARD_PROGRAM_ENABLEDand is not public.Redocly validates clean; warning count unchanged at 50, none in this file. Spectral does not run locally (see #795).